Add an example to the docs

svn path=/trunk/; revision=20935

diff --git a/ChangeLog b/ChangeLog
index a75a871c05dc3675a312eb8bff56e7714bc37827..f5e352ec89fe4ed220a3cf1516fa329490ab0df6 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2008-08-02  Matthias Clasen  <mclasen@redhat.com>
+
+       Bug 523950 – GtkTreeModelFilter's visible function may get an empty
+       row
+
+       * gtk/gtktreemodelfilter.c (gtk_tree_model_filter_set_visible_func):
+       Explain and show how iterators pointing to empty rows should be
+       handled in the visible function. Patch by Björn Lindqvist
+
 2008-08-02  Matthias Clasen  <mclasen@redhat.com>
 
        Bug 539733 – No way to control treeview separator height

diff --git a/gtk/gtktreemodelfilter.c b/gtk/gtktreemodelfilter.c
index 6d7116d57a2216428b7a23351eee2840ad4bcd42..1116cb0290dcc4462934863c3c9f2fcdd3893bc3 100644 (file)
--- a/gtk/gtktreemodelfilter.c
+++ b/gtk/gtktreemodelfilter.c
@@ -2884,6 +2884,29 @@ gtk_tree_model_filter_get_model (GtkTreeModelFilter *filter)
  * gtk_tree_model_filter_refilter() to keep the visibility information of 
  * the model uptodate.
  *
+ * Note that @func is called whenever a row is inserted, when it may still be
+ * empty. The visible function should therefore take special care of empty
+ * rows, like in the example below.
+ *
+ * <informalexample><programlisting>
+ * static gboolean
+ * visible_func (GtkTreeModel *model,
+ *               GtkTreeIter  *iter,
+ *               gpointer      data)
+ * {
+ *   /&ast; Visible if row is non-empty and first column is "HI" &ast;/
+ *   gchar *str;
+ *   gboolean visible = FALSE;
+ *
+ *   gtk_tree_model_get (model, iter, 0, &str, -1);
+ *   if (str && strcmp (str, "HI") == 0)
+ *     visible = TRUE;
+ *   g_free (str);
+ *
+ *   return visible;
+ * }
+ * </programlisting></informalexample>
+ *
  * Since: 2.4
  */
 void